home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / comms / other / pronet / developer / autodoc / pronetdrv.doc < prev    next >
Text File  |  1999-06-14  |  6KB  |  179 lines
  1. TABLE OF CONTENTS
  2.  
  3. pronet-driver/--Overview--
  4. pronet-driver/Exit
  5. pronet-driver/Init
  6. pronet-driver/Read
  7. pronet-driver/ReadFlush
  8. pronet-driver/ReadQuery
  9. pronet-driver/Write
  10. pronet-driver/--Overview--                         pronet-driver/--Overview--
  11.  
  12.  This file covers information on how to write custom ProNET drivers.
  13.  As is usual with my distributions ;-(, the API has changed again, but if
  14.  there was really a single custom driver out, it can be changed really easy.
  15.  
  16.  A ProNET driver is an ordinary executable residing in the DEVS:ProNET/
  17.  directory.  This executable will be loaded for every ProNET Unit requiring
  18.  it; it doesn't have to be reentrant.  The code is entered at the very
  19.  first position, which must contain the Init routine.
  20.  
  21.  >> CHANGES FROM V2 DRIVERS <<
  22.  
  23.  New in V3: Exit-Routine, Init-Flags = 1
  24.  New in v37: ReadFlush-Routine, Init-Flags (now called Version) = 2,
  25.     Write only one chunk, Write timeout support (three return codes now).
  26.  
  27. pronet-driver/Exit                                         pronet-driver/Exit
  28.  
  29.    NAME   
  30.     Exit -- Terminate a ProNET driver.
  31.  
  32.    SYNOPSIS
  33.     Exit();
  34.  
  35.     void Exit(void);
  36.  
  37.    FUNCTION
  38.     This function is called whenever pronet.device launches a new Unit
  39.     process. You must free all resources you allocated previously and
  40.     return after that.
  41.  
  42. pronet-driver/Init                                         pronet-driver/Init
  43.  
  44.    NAME   
  45.     Init -- Initialize a ProNET driver.
  46.  
  47.    SYNOPSIS
  48.     error = Init(drvdata, confstr, ID, version);
  49.     D0           A0       A1       D0  D1
  50.  
  51.     STRPTR Init(struct PNDrvData*, STRPTR, ULONG, ULONG);
  52.  
  53.    FUNCTION
  54.     This function is called whenever pronet.device launches a new Unit
  55.     process.
  56.  
  57.    INPUTS
  58.     drvdata - pointer to struct PNDrvData which must be filled out by
  59.         this routine.
  60.     confstr - pointer to the configuration string following the driver
  61.         ID.
  62.     ID - D0 contains the bytes "RST!" (not a pointer!). Check this to
  63.         prevent unwanted effects when your driver is started by
  64.         accident.
  65.     version - This number identifies the version of pronet.device that is
  66.         calling this driver. 0=V2, 1=V3, 2=v37; 0 and 1
  67.         should be rejected with error code NULL!.
  68.  
  69.    RESULT
  70.     error - NULL if everything went ok, or a pointer to an error string,
  71.         of which ProNET will make a copy and hand it to the calling
  72.         application. You could also return one of the magic cookies
  73.         as defined in devices/pronet.h for standard errors.
  74.  
  75.    SEE ALSO
  76.     devices/pronet.h
  77.  
  78. pronet-driver/Read                                         pronet-driver/Read
  79.  
  80.    NAME   
  81.     Read -- read the incoming packet data to a specified memory location.
  82.  
  83.    SYNOPSIS
  84.     Read(memptr);
  85.          A0
  86.  
  87.     void Read(APTR);
  88.  
  89.    FUNCTION
  90.     This function will only be called if a previous ReadQuery succeeded.
  91.     Here we will copy the packet's data to the specified memory location.
  92.  
  93.    INPUTS
  94.     memptr - memory location to which we shall copy
  95.  
  96. pronet-driver/ReadFlush                               pronet-driver/ReadFlush
  97.  
  98.    NAME   
  99.     ReadFlush -- Forget the incoming packet.
  100.  
  101.    SYNOPSIS
  102.     ReadFlush();
  103.  
  104.     void ReadFlush(void);
  105.  
  106.    FUNCTION
  107.     This function will only be called if a previous ReadQuery succeeded.
  108.     ProNET wants us to forget the complete packet.
  109.  
  110. pronet-driver/ReadQuery                               pronet-driver/ReadQuery
  111.  
  112.    NAME   
  113.     ReadQuery -- find out about an incoming packet.
  114.  
  115.    SYNOPSIS
  116.     length, destport, srcport = ReadQuery();
  117.     D0      D1        D2
  118.  
  119.     UWORD, UWORD, UWORD = ReadQuery(void);
  120.  
  121.    FUNCTION
  122.     This function is called whenever the Unit's task was woken up by
  123.     the signal bit you provided in drvdata->ReadSignalBit in the Init
  124.     routine. The signal bit can either be the signal bit of an
  125.     IORequest reply port or one triggered from an interrupt or
  126.     process set up by you.
  127.  
  128.     This function call is used to find out some basic info
  129.     about the incoming packet before reading the actual data.
  130.  
  131.    RESULT
  132.     length - number of bytes of the actual packet data (see NOTES)
  133.     destport - destination ProNET Port on this machine
  134.     srcport - source Port on the remote machine
  135.  
  136.    NOTES
  137.     If you find out that the ReadSignalBit was triggered by mistake,
  138.     you can return 0 in the length word, in which case ProNET will go
  139.     to sleep again. Otherwise it is *guaranteed* that either ReadFlush
  140.     or Read will be called lateron, no other driver routines will be
  141.     called in between.
  142.  
  143. pronet-driver/Write                                       pronet-driver/Write
  144.  
  145.    NAME   
  146.     Write -- Send a data packet to the remote machine.
  147.  
  148.    SYNOPSIS
  149.     error = Write(dataptr, length, destport, srcport);
  150.     D0            A0       D0      D1        D2
  151.  
  152.     ULONG Write(APTR, ULONG, UWORD, UWORD);
  153.  
  154.    FUNCTION
  155.     I guess this will always be the most complex function of a driver.
  156.     Try to get a connection to the remote machine and send the packet
  157.     as requested. A kind of flow control, like a timeout feature,
  158.     should be implemented.
  159.  
  160.    INPUTS
  161.     dataptr - pointer to the data to be transmitted
  162.     length - length of data to be transmitted. The length is limited
  163.         to 16384 bytes and it is even.
  164.     destport - destination Port on the remote machine
  165.     srcport - source Port on this machine
  166.  
  167.    RESULT
  168.     error - 0  if packet could be sent without trouble.
  169.         -1 if the line is currently busy -- pronet.device will then
  170.            try again later.
  171.         1  if the remote machine does not respond. The application
  172.            will be notified in this case, CMD_WRITE returns with
  173.            an error (PNDERR_DESTINATION_GONE).
  174.  
  175.    NOTES
  176.     Your driver is responsible for correct transmission of the data,
  177.     by using checksums or similar mechanisms.
  178.  
  179.